2020.2

Integrations

On this page:

JavaScript Mapper Build Configuration Patch Function

JavaScript Mapper Build Configuration Patch Function

Once Policy Manager has constructed an outgoing configuration with your export template and preRenderPolicy method, it uses your buildConfigurationPatch method to construct the final config change commands to be sent to the device.

The buildConfigurationPatch method takes a single argument (existingAndDesired).

Argument Description
existingAndDesired An object describing the current state of the device, and the expected final state of the device.


Array Description
existingAndDesired.existingTargets An array mapping target names to policy names in the current state of the device. This list is exhaustive, and will contain entries with null policy names for unlinked targets.
existingAndDesired.desiredTargets An array mapping target names to policy names in the desired state of the device. This list is non-exhaustive, and will only contain entries for targets which are linked to a policy.
existingAndDesired.existingPolicies An array of Policy Manager policy entities describing the ACL configuration currently on the device.
existingAndDesired.desiredPolicies An array of objects containing several fields:
existingAndDesired.desiredPolicies[*].name : The name of the policy in Policy Manager.
existingAndDesired.desiredPolicies[*].iapPolicy : The full policy entity from Policy Manager.
existingAndDesired.desiredPolicies[*].prerendered : The result of calling your preRenderPolicy method with the above policy entity.
existingAndDesired.desiredPolicies[*].rendered : The result of rendering your export template with the above prerendered policy.

The output of buildConfigurationPatch is expected to conform to the format of generic configuration patches supported by device brokers in IAP. See the associated documentation (Configuration Patches) for configuration patch structure.

Examples

Example existingAndDesired input to Policy Manager's internal Cisco IOS integration:

{
  "existingTargets": [
    {
      "GigabitEthernet1_in": null
    },
    {
      "GigabitEthernet1_out": "pm-test-ext-1"
    },
    {
      "Loopback11_in": null
    },
    {
      "Loopback11_out": null
    },
    {
      "VirtualPortGroup0_in": null
    },
    {
      "VirtualPortGroup0_out": null
    }
  ],
  "desiredTargets": [
    {
      "GigabitEthernet1_out": "pm-test-ext-1"
    }
  ],
  "existingPolicies": [
    {
      "name": "pm-test-ext-1",
      "policyType": "acl",
      "addressType": "IPv4",
      "rules": [
        {
          "name": "pm-test-ext-1_rule0",
          "enabled": true,
          "policyType": "acl",
          "action": "permit",
          "sourceNetworks": [
            {
              "addressType": "IPv4",
              "canonical": "0.0.0.0/0",
              "address": "0.0.0.0",
              "prefixLength": 0,
              "netmask": "0.0.0.0",
              "hostmask": "255.255.255.255"
            }
          ],
          "destinationNetworks": [
            {
              "addressType": "IPv4",
              "canonical": "0.0.0.0/0",
              "address": "0.0.0.0",
              "prefixLength": 0,
              "netmask": "0.0.0.0",
              "hostmask": "255.255.255.255"
            }
          ],
          "services": [
            {
              "traffic": {
                "protocol": 6
              }
            }
          ],
          "logging": true
        },
        {
          "name": "pm-test-ext-1_rule1",
          "enabled": true,
          "policyType": "acl",
          "action": "permit",
          "sourceNetworks": [
            {
              "addressType": "IPv4",
              "canonical": "0.0.0.0/0",
              "address": "0.0.0.0",
              "prefixLength": 0,
              "netmask": "0.0.0.0",
              "hostmask": "255.255.255.255"
            }
          ],
          "destinationNetworks": [
            {
              "addressType": "IPv4",
              "canonical": "0.0.0.0/0",
              "address": "0.0.0.0",
              "prefixLength": 0,
              "netmask": "0.0.0.0",
              "hostmask": "255.255.255.255"
            }
          ],
          "services": [
            {
              "traffic": {
                "protocol": 1
              }
            }
          ]
        }
      ]
    }
  ],
  "desiredPolicies": [
    {
      "name": "pm-test-ext-1",
      "iapPolicy": {
        "name": "pm-test-ext-1",
        "policyType": "acl",
        "addressType": "IPv4",
        "rules": [
          {
            "name": "pm-test-ext-1_rule0",
            "enabled": true,
            "policyType": "acl",
            "action": "permit",
            "sourceNetworks": [
              {
                "addressType": "IPv4",
                "canonical": "0.0.0.0/0",
                "address": "0.0.0.0",
                "prefixLength": 0,
                "netmask": "0.0.0.0",
                "hostmask": "255.255.255.255"
              }
            ],
            "destinationNetworks": [
              {
                "addressType": "IPv4",
                "canonical": "0.0.0.0/0",
                "address": "0.0.0.0",
                "prefixLength": 0,
                "netmask": "0.0.0.0",
                "hostmask": "255.255.255.255"
              }
            ],
            "services": [
              {
                "traffic": {
                  "protocol": 6
                }
              }
            ]
          },
          {
            "name": "pm-test-ext-1_rule1",
            "enabled": true,
            "policyType": "acl",
            "action": "permit",
            "sourceNetworks": [
              {
                "addressType": "IPv4",
                "canonical": "0.0.0.0/0",
                "address": "0.0.0.0",
                "prefixLength": 0,
                "netmask": "0.0.0.0",
                "hostmask": "255.255.255.255"
              }
            ],
            "destinationNetworks": [
              {
                "addressType": "IPv4",
                "canonical": "0.0.0.0/0",
                "address": "0.0.0.0",
                "prefixLength": 0,
                "netmask": "0.0.0.0",
                "hostmask": "255.255.255.255"
              }
            ],
            "services": [
              {
                "traffic": {
                  "protocol": 1
                }
              }
            ]
          }
        ]
      },
      "prerendered": {
        "name": "pm-test-ext-1",
        "policyType": "acl",
        "addressType": "IPv4",
        "rules": [
          {
            "name": "pm-test-ext-1_rule0",
            "enabled": true,
            "policyType": "acl",
            "action": "permit",
            "sourceNetworks": [
              "any"
            ],
            "destinationNetworks": [
              "any"
            ],
            "services": [
              {
                "traffic": {
                  "protocol": 6
                },
                "protocol": "tcp"
              }
            ]
          },
          {
            "name": "pm-test-ext-1_rule1",
            "enabled": true,
            "policyType": "acl",
            "action": "permit",
            "sourceNetworks": [
              "any"
            ],
            "destinationNetworks": [
              "any"
            ],
            "services": [
              {
                "traffic": {
                  "protocol": 1
                },
                "protocol": "icmp"
              }
            ]
          }
        ]
      },
      "rendered": "\nExtended IP access list pm-test-ext-1\n permit tcp any any\n permit icmp any any\n\n"
    }
  ]
}

Example configuration patch output from the above operation:

[
  {
    "parents": [
      "interface GigabitEthernet1"
    ],
    "old": "ip access-group pm-test-ext-1 out",
    "new": ""
  },
  {
    "parents": [],
    "old": "ip access-list extended pm-test-ext-1",
    "new": ""
  },
  {
    "parents": [
      "ip access-list extended pm-test-ext-1"
    ],
    "old": "",
    "new": "permit tcp any any"
  },
  {
    "parents": [
      "ip access-list extended pm-test-ext-1"
    ],
    "old": "",
    "new": "permit icmp any any"
  },
  {
    "parents": [
      "interface GigabitEthernet1"
    ],
    "old": "",
    "new": "ip access-group pm-test-ext-1 out"
  }
]

Order of operations for the above configuration patches:

  1. Unlink the policy named pm-test-ext-1 from the interface GigabitEthernet1_out on the device.

    {
  "parents": [
    "interface GigabitEthernet1"
  ],
  "old": "ip access-group pm-test-ext-1 out",
  "new": ""
}

  2. Delete the existing version of pm-test-ext-1 on the device.

    {
  "parents": [],
  "old": "ip access-list extended pm-test-ext-1",
  "new": ""
}

  3. Re-create pm-test-ext-1 on the device. Note there are two rules which exist in this policy.

    {
  "parents": [
    "ip access-list extended pm-test-ext-1"
  ],
  "old": "",
  "new": "permit tcp any any"
},
{
  "parents": [
    "ip access-list extended pm-test-ext-1"
  ],
  "old": "",
  "new": "permit icmp any any"
}

  4. Link the new version of the pm-test-ext-1 policy to the interface GigabitEthernet1_out.

    {
  "parents": [
    "interface GigabitEthernet1"
  ],
  "old": "",
  "new": "ip access-group pm-test-ext-1 out"
}